# 构建性能分析

进行构建性能分析可以帮助你确定项目中的性能瓶颈，从而采取针对性的优化。

## 使用 Rsdoctor

Rsdoctor 是一个构建分析工具，能够可视化地展示各个 loaders 和 plugins 的编译耗时。

请参考 [使用 Rsdoctor](/guide/debug/rsdoctor) 了解更多。

## Node.js profiling

当 Rsbuild 执行一次构建时，会包含 JavaScript 和 Rust 两侧的代码运行开销，以及 JavaScript 和 Rust 之间的数据通信开销。

通常而言，JavaScript 侧的性能开销会大于 Rust 侧，你可以使用 Node.js 的 profiling 来分析 JS 侧的开销，这有助于发现 JS 侧的性能瓶颈。

例如，进行 [CPU profiling](https://nodejs.org/docs/v20.17.0/api/cli.html#--cpu-prof) 分析，在项目根目录执行以下命令：

```bash
# dev
node --cpu-prof ./node_modules/@rsbuild/core/bin/rsbuild.js dev

# build
node --cpu-prof ./node_modules/@rsbuild/core/bin/rsbuild.js build

# 设置更高精度的采样间隔
node --cpu-prof --cpu-prof-interval=100 ./node_modules/@rsbuild/core/bin/rsbuild.js build
```

以上命令执行后会生成一个 `*.cpuprofile` 文件，我们可以使用 [speedscope](https://github.com/jlfwong/speedscope) 来可视化查看该文件：

```bash
# 安装 speedscope
npm install -g speedscope

# 查看 cpuprofile 内容
# 请将文件名替换为本地文件的名称
speedscope CPU.date.000000.00000.0.001.cpuprofile
```

## Rspack profiling

Rsbuild 支持使用 `RSPACK_PROFILE` 环境变量来对 Rspack 进行构建性能分析。

```json title="package.json"
{
  "scripts": {
    "dev:profile": "RSPACK_PROFILE=OVERVIEW rsbuild dev",
    "build:profile": "RSPACK_PROFILE=OVERVIEW rsbuild build"
  }
}
```

由于 Windows 不支持上述用法，你也可以使用 [cross-env](https://npmjs.com/package/cross-env) 来设置环境变量，这可以确保在不同的操作系统中都能正常使用：

```json title="package.json"
{
  "scripts": {
    "dev:profile": "cross-env RSPACK_PROFILE=OVERVIEW rsbuild dev",
    "build:profile": "cross-env RSPACK_PROFILE=OVERVIEW rsbuild build"
  },
  "devDependencies": {
    "cross-env": "^7.0.0"
  }
}
```

当 build 命令执行完成，或是 dev server 被关闭时，Rsbuild 会在当前目录下生成一个 `.rspack-profile-${timestamp}-${pid}` 文件夹，其中包含 `rspack.pftrace` 文件（在 1.4.0 之前的版本中为 `trace.json`），该文件由 Rspack 基于 [tracing](https://github.com/tokio-rs/tracing) 细粒度地记录了各个阶段的耗时，可以使用 [ui.perfetto.dev](https://ui.perfetto.dev/) 进行查看。

:::tip

- 在关闭 dev server 时，优先使用 `CTRL + D` 关闭，而不是 `CTRL + C`，这可以确保 Rspack 能够完整地记录性能数据。
- 生成的 `trace.json` 文件体积较大，如果需要分享给他人查看，可以压缩为 zip 文件来减小体积。
- 关于 Rspack 性能分析的更多用法，可参考 [Rspack - Tracing](https://rspack.rs/zh/contribute/development/tracing)。

:::
